== RELEASE NOTES ==
v4.6.2.1907 features the following:
* (Wiki) Publish 2019-05 English Wikipedia
* (PC) Fix Category not working for en.w
* (PC) Fix pages not loading due to infinite loop
* (PC) Various parser fixes

For more details about this release, please see:
* http://xowa.org/home/wiki/Change_log.html

See the CHANGE LOG below for a complete list of items specific to this release.

== CONTACT ==
XOWA's website is at http://xowa.org . All files are at https://github.com/gnosygnu/xowa/releases/

If you encounter issues, please post to https://github.com/gnosygnu/xowa/issues

== LICENSE ==
XOWA is licensed under the terms of the General Public License (GPL) Version 3,
or alternatively under the terms of the Apache License Version 2.0.

See /xowa/bin/any/xowa/LICENSE.txt for more information. On a Windows system  where XOWA is unzipped to C:\xowa,
the full fill path would be C:\xowa\bin\any\xowa\LICENSE.txt

== INSTALL ==
=== FILES ===
The xowa_app_*** archives have all the files necessary for xowa to run, including the main jars, XULRunner, languages, etc..

The paths below are recommendations. Please feel free to choose any other.

Finally, note that "/xowa/" refers to the XOWA root directory. For example, if you're on a Windows system and unzipped XOWA to "C:\xowa", then "/xowa/wiki/en.wikipedia.org" means "C:\xowa\wiki\en.wikipedia.org"

=== REQUIREMENTS ===
* Java 1.7+
: If you do not have Java 1.7 installed, then please install the latest Java from http://www.java.com/en/download/manual.jsp
: On Ubuntu Linux, you can use OpenJDK by running 'sudo apt-get install openjdk-7-jre'.
* Compression/Decompression program ("unzip")
: The XOWA files will be compressed. If your Operating System does not natively support decompressing, please install 7-Zip from http://7-zip.org.
* 512 MB RAM
: XOWA can run on lower memory machines, but 512 MB is needed for importing the larger wikis (EX: en.wikipedia.org; commons.wikimedia.org)

=== OPERATING SYSTEMS ===
===== Windows 64-bit =====
* Download 'xowa_app_windows_64_v*.*.*.*.zip'
* Unzip to 'C:\xowa'. When you are done you should have a file called 'C:\xowa\xowa_64.exe' as well as many others
* Double-click 'xowa_64.exe'
* If "xowa_64.exe" fails, you may have a 32-bit Java installation. Try the "Windows 32-bit" installation below

===== Windows 32-bit =====
[NOTE: This is the same as Windows 64-bit, except the non-"_64" files are used]
* Download 'xowa_app_windows_v*.*.*.*.zip'
* Unzip to 'C:\xowa'. When you are done you should have a file called 'C:\xowa\xowa.exe' as well as many others
* Double-click 'xowa.exe'

==== Linux 64-bit ====
* Download 'xowa_app_linux_64_v*.*.*.*.zip'
* Unzip to '/home/your_user_name/xowa/'. When you are done you should have a file called '/home/your_user_name/xowa/xowa_linux_64.jar' as well as many others
* Open a terminal and run "sh /home/your_user_name/xowa/xowa_linux_64.sh"
* If "xowa_linux_64.sh" doesn't work, run "java -Xmx256m -jar /home/your_user_name/xowa/xowa_linux_64.jar"

==== Linux ====
[NOTE: This is the same as Linux 64-bit, except the non-"_64" files are used]
* Download 'xowa_app_linux_v*.*.*.*.zip'
* Unzip to '/home/your_user_name/xowa/'. When you are done you should have a file called '/home/your_user_name/xowa/xowa_linux.jar' as well as many others
* Open a terminal and run "sh /home/your_user_name/xowa/xowa_linux.sh"
* If "xowa_linux.sh" doesn't work, run "java -Xmx256m -jar /home/your_user_name/xowa/xowa_linux.jar"

==== Mac OS X 64-bit ====
* Download 'xowa_app_macosx_64_v*.*.*.*.zip'
* Unzip to '/Users/your_user_name/xowa/'. When you are done you should have a file called '/Users/your_user_name/xowa/xowa_macosx_64.jar' as well as many others
* Open a terminal by doing Finder -> Applications -> Utilities -> Terminal
* Run "sh /Users/your_user_name/xowa/xowa_macosx_64"
* If "xowa_macosx.sh" doesn't work, run "java -Xmx256m -d32 -XstartOnFirstThread -jar /Users/your_user_name/xowa/xowa_macosx_64.jar"

==== Mac OS X 32-bit ====
[NOTE: This is the same as Mac OS X 64-bit, except the non-"_64" files are used]
* Download 'xowa_app_macosx_v*.*.*.*.zip'
* Unzip to '/Users/your_user_name/xowa/'. When you are done you should have a file called '/Users/your_user_name/xowa/xowa_macosx.jar' as well as many others
* Open a terminal by doing Finder -> Applications -> Utilities -> Terminal
* Run "sh /Users/your_user_name/xowa/xowa_macosx"
* If "xowa_macosx.sh" doesn't work, run "java -Xmx256m -d32 -XstartOnFirstThread -jar /Users/your_user_name/xowa/xowa_macosx.jar"


== USAGE ==
=== Setting up Simple Wikipedia ===
* Once XOWA loads, you will see the Main Page
* Go to the "New users" section and click the link for "Set up Simple Wikipedia". Wait about 3 minutes for the wiki to download and install. When it is finished, it will open Simple Wikipedia
* Browse Simple Wikipedia. When you are done, click on the Main Page link under XOWA in the left hand navigation bar.

Here are some example pages to visit (you can copy and paste these into the address bar):
* http://simple.wikipedia.org/wiki/Gothic_architecture
* http://simple.wikipedia.org/wiki/Saturn_(planet)
* http://simple.wikipedia.org/wiki/Chess
* http://simple.wikipedia.org/wiki/World_History

=== Setting up other wikis ===
* If you want to load English Wikipedia or any other wiki, do any of the following:
** Click on "Import Online" on the XOWA Main Page
** Enter "Help:Import/List" in the address bar near the top of the screen
** Using the Menu, do "Tools" -> "Import online"

=== Downloading offline thumbs ===
* If you want to download a complete set of images for your wiki, see the following links:
** For instructions, see: http://gnosygnu.github.io/xowa/setup_simplewiki.html and http://gnosygnu.github.io/xowa/setup_enwiki.html
** For a list of image databases see http://gnosygnu.github.io/xowa/image_dbs.html or https://archive.org/search.php?query=xowa


== TROUBLESHOOTING ==
=== Windows ===
==== Administrator privileges ====
If you're on Windows Vista, 7, 8, or 10, try running the program with administrator privileges. You can do so by right-clicking on the exe and choosing "Run as administrator"

==== XULRunner ====
Try double-clicking the xulrunner.exe.
* Go to C:\xowa\bin\windows_64\xulrunner_v24 (or on 32-bit machines, C:\xowa\bin\windows\xulrunner_v24)
* Double-click xulrunner.exe
* You should get a message box that starts off with "Mozilla XUL Runner "
* If it fails with "Can't start because MSVCR100.dll is missing...try reinstalling to fix...", then you will need to install the Visual C++ redistributable. See http://sourceforge.net/p/xowa/discussion/general/thread/cc7d867d/?limit=25&page=1#8d38 or http://answers.microsoft.com/en-us/windows/forum/windows_7-windows_programs/trying-to-open-computer-management-the-program/5c9d301a-2191-4edb-916e-5e4958558090?auth=1

==== Run by command-line ====
If the .exe fails, you can try running the jar by the command-line.
* Click on Start and go to Run
* Enter "cmd". A console shows up.
* Enter "java -Xmx256m -jar C:\xowa\xowa_windows_64.jar"

==== Run using a specific JRE ====
* Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html
* Click the "Download" button under "JRE"
**  Choose the Windows x86 version
::  As of the time of this writing, "Windows x86 Offline" links to http://download.oracle.com/otn-pub/java/jdk/7u40-b43/jre-7u40-windows-i586.exe
**  Choose an installation folder. For example, "C:\Program Files (x86)\Java\jre7_x86"
**  After installing, run the following in the command-line: "C:\Program Files (x86)\Java\jre7_x86\bin\java" -Xmx256m -jar C:\xowa\xowa_windows.jar

==== Java installation ====
Check that your Java installation is installed correctly
* Run the following in the command-line: "java -version"
* It should report "java version "1.7****" or higher

==== Arabic characters in path ====
XOWA cannot run in a folder with Arabic characters due to a limitation in one of its sub-components (SWT). For example, C:\موسوعات\XOWA will not work. On the other hand, C:\encyclopedia\XOWA will work. For more info, see https://bugs.eclipse.org/bugs/show_bug.cgi?id=443044

=== Mac OS X ===
==== Missing Java ====
If you get a "No Java runtime present" you will need to set up Java on your machine. There are two options:
* Update to the latest Java 6 by going to http://support.apple.com/kb/DL1572?viewlocale=en_US
: This will be simpler. However, note that Java 6 is an older obsolete version.
* Download Java by going to java.com
: This will be the most up-to-date Java version. However it requires additional steps.

To install Java, do the following:
* Find your Java runtime: Run "/Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java -version" in the terminal to verify the path
* Assuming your java is at the above location, run XOWA by doing either of the following
: (1) Run the following from the terminal:
:     /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java -Xmx256m -XstartOnFirstThread -Xdock:name=XOWA /Users/your_user_name/xowa/xowa_macosx_64.jar
: (2) Change your official java to the plugin version and then run xowa_macosx_64.sh
:     sudo ln -fs /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java /usr/bin/java

=== Linux ===
==== Symbolic links sometimes fails ====
XOWA sometimes fails to import large wikis when symbolic links are in the directory. See: https://github.com/gnosygnu/xowa/issues/16#issuecomment-127458416

==== Downloads fail with "ssl peer shut down incorrectly" ====
On some systems, XOWA fails to download any files with the message "ssl peer shut down incorrectly". The underlying cause is currently unknown, and any insight is appreciated here. It may be related to old Java versions or atypical network setups (VPN?).

The fix was to specify https.protocols=TLSv1 in the startup. For example:
* On Windows: "java -Dhttps.protocols=TLSv1 -Xmx256m -jar xowa_windows_64.jar"
* On Linux: "export SWT_GTK3=0 && java -Dhttps.protocols=TLSv1 -Xmx256m -jar xowa_linux_64.jar"
* On Mac OS X: "java -Dhttps.protocols=TLSv1 -Xmx256m -jar xowa_macosx_64.jar"

=== OpenSUSE and "java.lang.InternalError at sun.security.ec.SunEC.initialize" ===
Recent versions of OpenSuse and Java 1.8 may throw an error like the following:

    Exception in thread "wiki.import" java.lang.InternalError
    at sun.security.ec.SunEC.initialize(Native Method)

To workaround this issue, try the following:

* Open up the following file in text editor:
: /xowa/user/anonymous/app/cfg/os.lnx_64.gfs
* Change line 17 as per the following:
: old: browser_type = 'mozilla'; // 'mozilla' or 'webkit'
: new: browser_type = 'webkit'; // 'mozilla' or 'webkit'

For more info, see https://github.com/gnosygnu/xowa/issues/151

=== Minimal XFCE desktop may fail with org.eclipse.swt.SWTError: No more handles === 
Running on a minimal XFCE desktop may throw an error like the following

    Error: org.eclipse.swt.SWTError: No more handles
    Stack: org.eclipse.swt.SWT.error(Unknown Source)
    org.eclipse.swt.SWT.error(Unknown Source)

To workaround this issue, install the following libraries:
* libjavascriptcoregtk-1_0-0
* libwebkitgtk-1_0-0
* libwebkitgtk2-lang

For more info, see https://github.com/gnosygnu/xowa/issues/151

=== Setting up HTTP Server for Linux ===
* Change xowa_linux_64.sh to something like the following: "java -Dhttp.proxyHost=YOUR_PROXY_HOST -Dhttp.proxyPort=YOUR_PROXY_PORT"
* Install "java-1_8_0-openjdk-headless and libcap-progs"
* (Optional: To listen on port 80) Run "setcap CAP_NET_BIND_SERVICE=+eip /usr/lib64/jvm/jre-1.8.0-openjdk/bin/java"

== CHANGE LOG ==
== v4.6.2.1907 (2019-07-24) ==
=== Wikis ===
* Package: Publish 2019-05 English Wikipedia.
: Issue: https://github.com/gnosygnu/xowa/issues/

=== PC ===
'''major'''
* Category: Fix Category not working for en.w. {detected by desb42}
: Resolved by: Replace UNION with sequential loading from each catlink db.
: Issue: https://github.com/gnosygnu/xowa/issues/268

* Scribunto: Fix infinite loop on some en.w pages when finding on ucs-2 chars. {detected by desb42}
: Resolved by: Adjust index position correctly for ucs-2 strings.
: Example: {{WP7a|got|Gothic}}.
: Links: https://en.wikipedia.org/wiki/List_of_Wikipedias
: Issue: https://github.com/gnosygnu/xowa/issues/506

* Luaj: Fix infinite loop on some en.w pages when matching Unicode Alphabetic chars. {detected by desb42}
: Resolved by: Support PCRE character definitions for Luaj Regex.
: Issue: https://github.com/gnosygnu/xowa/issues/502

'''significant'''
* Parser.Tidy: Add vnu as additional tidy engine. {contributed by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/417

* Xtns.TemplateStyles: Cache TemplateStyles for HTML databases.
: Issue: https://github.com/gnosygnu/xowa/issues/482

* Scribunto: Use Luaj for pattern-matching (instead of Java Regex).
: Issue: https://github.com/gnosygnu/xowa/issues/413

* Wikibase: Add qualifiers-order to GetEntityStatements. {contributed by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/374

* Parser.Wikibase: Fix 'qid not found' errors in session.txt. {contributed by desb42}
: Resolved by: Retrieve by label if pid is not present; also, return pid, not label.
: Issue: https://github.com/gnosygnu/xowa/issues/354

* Css: Show external-link icon and other css effects. {contributed by desb42}
: Resolved by: Add 'mw-parser-output' to main div.
: Links: https://en.wikipedia.org/wiki/Earth
: Issue: https://github.com/gnosygnu/xowa/issues/274

* Sqlite: Allow faster wiki loading for read-only devices. {requested by ZebraFromPluto}
: Resolved by: Add option for read-only detection.
: Links: home/wiki/Special:XowaCfg?grp=xowa.app.dbs
: Issue: https://github.com/gnosygnu/xowa/issues/509

* Xtn.Popups: Disable popups by default for en.wiktionary.org. {suggested by ZebraFromPluto}
: Links: home/wiki/Special:XowaCfg?grp=xowa.addon.popups
: Issue: https://github.com/gnosygnu/xowa/issues/511

* HTTP Server: Fix links not working in left nav bar. {detected by anonymous}
: Resolved by: Parse links with trailing slash.
: Issue: https://github.com/gnosygnu/xowa/issues/459

'''minor'''
* Xtn.Translate: Fix 'callParserFunction: function was not found: function=#translation' on many commons pages. {assisted by desb42}
: Resolved by: Add #translation function with no implementation.
: Example: {{#translation}}.
: Issue: https://github.com/gnosygnu/xowa/issues/445

* Parser.Wikibase: Fix 'Module:ResolveEntityId:31 attempt to index ?' on several dozen en.w biology pages.
: Resolved by: Return null instead of empty string if invalid title passed to getEntityId.
: Links: https://en.wikipedia.org/wiki/Nicoletella
: Issue: https://github.com/gnosygnu/xowa/issues/415

* Parser.TemplateStyles: Fix NullPointerException on a few dozen en.w Portal pages.
: Resolved by: Check if title is null.
: Links: https://en.wikipedia.org/wiki/Portal:Switzerland
: Issue: https://github.com/gnosygnu/xowa/issues/416

* ParserFunctions: Fix "Expression error: Missing operand for =" on some en.w pages. {detected by desb42}
: Resolved by: Increase precedence of "E" over "ln" and other operations.
: Example: {{#expr:ln2E+3}}.
: Issue: https://github.com/gnosygnu/xowa/issues/397

* Scribunto: Fix '@libraryUtil.lua:13 bad argument #1 to gmatch (string expected, got nil)' on a few en.w pages.
: Resolved by: Set frame title for pages when invoking Scribunto code.
: Links: https://en.wikipedia.org/wiki/Wikipedia:Categories_for_discussion 
: Issue: https://github.com/gnosygnu/xowa/issues/476

* Scribunto: Fix 'invoke failed: ... {{#invoke:Navbar|navbar}}' on some en.w pages. {detected by desb42}
: Resolved by: Add frame_ttl to all Xot_invk_tkn.
: Links: https://en.wikipedia.org/wik/2003_Tippeligaen
: Issue: https://github.com/gnosygnu/xowa/issues/503

* Scribunto: Fix 'https%3A%2F%2F' showing up in reference links on some en.w pages. {detected by desb42}
: Resolved by: Synchronize mw.uri.lua file with changes for uri.encode(s, 'WIKI').
: Links: https://en.wikipedia.org/wik/Christmas
: Issue: https://github.com/gnosygnu/xowa/issues/504

* Luaj: Fix invalid url-encoding for non-ASCII characters like 'æ'. {detected by desb42}
: Resolved by: Substring by bytes, not string, to handle malformed strings.
: Issue: https://github.com/gnosygnu/xowa/issues/504

* Scribunto: Fix query args showing up on en.w Template pages. {detected by desb42}
: Resolved by: Encode key / val in GetUrl.
: Issue: https://github.com/gnosygnu/xowa/issues/465

* Scribunto: Fix 'NullPointerException in Module:Wikidata:622' on some de.w pages. {contributed by desb42}
: Resolved by: Ignore snak if novalue.
: Issue: https://github.com/gnosygnu/xowa/issues/481

* Scribunto: Fix 'Module:Exception:2 attempt to index ? (a nil value)' on some en.u pages. {detected by desb42}
: Links: https://en.wikiversity.org/wiki/Web_Science/Part2:_Emerging_Web_Properties/Hearding_Behavior/Summary,_Further_readings,_Homework
: Issue: https://github.com/gnosygnu/xowa/issues/475

* Xtn.Cldr: Fix 'Module:wikipedia:49 The Wikimedia language code goh is not valid' on some en.d pages. {detected by desb42}
: Resolved by: Check CldrNames for IsKnownLanguageTag.
: Issue: https://github.com/gnosygnu/xowa/issues/388

* Scribunto: Fix 'Template:Template:Page' does not exist. {detected by desb42}
: Resolved by: Apply namespace argument only if in main namespace.
: Example: =mw.title.new("Template:Test", 'File').
: Issue: https://github.com/gnosygnu/xowa/issues/473

* HttpServer: Navigate to an error page for invalid titles like "Earth]". {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/480

* Parser.Comment: Fix run-on paragraph if comment is added between blank linkes. {contributed by desb42}
: Resolved by: Terminate comment if new-line found.
: Links: https://en.wikisource.org/wiki/Three_Villages/2_Shirley
: Issue: https://github.com/gnosygnu/xowa/issues/437

* Xtn.SyntaxHighlight: Highlight lines if 'highlight' is passed but 'line' is not. {contributed by desb42}
: Example: &lt;syntaxhighlight lang="text" highlight="4-7">.
: Links: https://commons.wikimedia.org/wiki/Template:TemplateBox/doc/example-value
: Issue: https://github.com/gnosygnu/xowa/issues/498

* Scribunto: Format date correctly for years with less than 4 digits (EX: +0065 -> 65 x> 2065). {contributed by desb42}
: Example: "+0065-12-01" -> "65-12-01" x> "2065-12-01".
: Issue: https://github.com/gnosygnu/xowa/issues/500

* Language: Escape left-to-right / right-to-left marks in names.json ('\xE2\x80\x8E'  to '\u200E'). {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/501

* Parser: Remove unnecessary html from anchor.encode. {detected by desb42}
: Resolved by: Parse html in internal link captions.
: Links: &#91;&#91;File:A.png|<span>b</span>]]
: Issue: https://github.com/gnosygnu/xowa/issues/460

* Parser: Handle UTF-8 characters in attribute keys / values. {contributed by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/457

* Json: Parse surrogate-pairs correctly in unicode-escaped strings. {contributed by desb42}
: Example: \ud83c\udf0.
: Issue: https://github.com/gnosygnu/xowa/issues/487

* Parser: Change encoding of html id to encode fewer characters.
: Issue: https://github.com/gnosygnu/xowa/issues/462

'''trivial'''
* User.Logs: Delete log folders if logs are disabled. {requested by ZebraFromPluto}
: Issue: https://github.com/gnosygnu/xowa/issues/510

* Html: Change self-link pages from &lt;b> to &lt;a class='mw-selflink selflink'>. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/478

* Css: Change css jump-to class from 'mw-navigation' to 'mw-head'. {detected by desb42}
: Links: https://phabricator.wikimedia.org/source/Vector/browse/master/includes/templates/index.mustache$20
: Issue: https://github.com/gnosygnu/xowa/issues/394

* Json: Skip forward by 5 characters, not 4 for unicode sequences. {contributed by desb42}
: Example: \u0022.
: Issue: https://github.com/gnosygnu/xowa/issues/486

* Parser: Do not parse '&amp;#x;' as byte 0. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/494

'''dev'''
* Mass_parse: Fix mass_parse failing due to 'counts do not match; same key is either added twice, or delete failed'. {detected by desb42}
: Resolved by: Use page_cache hashCode, not wiki hashCode.
: Issue: https://github.com/gnosygnu/xowa/issues/514

* Mass_parse: Add xomp_stats to track time per page (and other attributes). {suggested by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/456

* Mass_parse: Change page_cache to LRU cache.
: Issue: https://github.com/gnosygnu/xowa/issues/483

* Dev: Rename test files to use '_tst' and '_fxt' convention. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/512

* Dev: Create Maven artifact. {contributed by t}
: Issue: https://github.com/gnosygnu/xowa/issues/427

